/**
 * @file Frame_PID.h
 * @brief 通用PID控制器库头文件
 * @details 提供PID控制器的结构体定义和函数接口，支持输出限制、积分抗饱和和灵活的模式配置。
 */

#ifndef __FRAME_PID_H__
#define __FRAME_PID_H__

#ifdef __cplusplus  ///<兼容C++调用
extern "C" {
#endif

/**
 * @brief PID控制器结构体
 * @note 用户需通过PID_Init函数初始化后使用。
 */
typedef struct {
    float kp;               ///< 比例增益
    float ki;               ///< 积分增益
    float kd;               ///< 微分增益
    float setpoint;         ///< 目标设定值
    float integral;         ///< 积分项累积值（内部使用）
    float previous_error;   ///< 上一次的误差（内部使用）
    float output;           ///< 控制器输出值（内部使用）
    float output_min;       ///< 输出最小值限制（例如执行器的最低功率）
    float output_max;       ///< 输出最大值限制（例如执行器的最高功率）
    float integral_min;     ///< 积分项最小值（抗积分饱和）
    float integral_max;     ///< 积分项最大值（抗积分饱和）
    int use_integral;       ///< 是否启用积分项（1=启用，0=禁用）
    int use_derivative;     ///< 是否启用微分项（1=启用，0=禁用）
} PIDController;

/**
 * @brief 初始化PID控制器
 * @param pid        PID控制器实例指针
 * @param kp         比例增益
 * @param ki         积分增益
 * @param kd         微分增益
 * @param setpoint   目标设定值
 * @param output_min 输出最小值限制
 * @param output_max 输出最大值限制
 * @param integral_min 积分项最小值限制（抗饱和）
 * @param integral_max 积分项最大值限制（抗饱和）
 * @param use_integral 是否启用积分项（1=启用，0=禁用）
 * @param use_derivative 是否启用微分项（1=启用，0=禁用）
 */
void PID_Init(
    PIDController *pid,
    float kp, float ki, float kd,
    float setpoint,
    float output_min, float output_max,
    float integral_min, float integral_max,
    int use_integral, int use_derivative
);

/**
 * @brief 更新PID控制器并计算输出
 * @param pid            PID控制器实例指针
 * @param current_value  当前测量值（例如传感器读数）
 * @return PID计算后的输出值（已应用输出限制）
 */
float PID_Update(PIDController *pid, float current_value);

/**
 * @brief 重置PID控制器的内部状态（积分项和上一次误差）
 * @param pid PID控制器实例指针
 */
void PID_Reset(PIDController *pid);

#ifdef __cplusplus
}
#endif

#endif // PID_CONTROLLER_H